=begin pod

=TITLE class Telemetry::Sampler

=SUBTITLE Telemetry Instrument Pod

    =begin code :preamble<class Telemetry { }>
    class Telemetry::Sampler { }
    =end code

B<Note: > This class is a Rakudo-specific feature and not standard Perl 6.

=begin code
use Telemetry;
$*SAMPLER.set-instruments(<Usage ThreadPool>); # default setting
=end code

One usually does not create any C<Telemetry::Sampler> objects: when the
L<Telemetry|/type/Telemetry> module is loaded, a C<Telemetry::Sampler> object
is automatically created in the C<$*SAMPLER> dynamic variable.

An object of the C<Telemetry::Sampler> class knows about which instruments
to use when making a snapshot.

=head2 method new

  method new(Telemetry::Sampler: @instruments --> Telemetry::Sampler:D)

The C<new> method takes a list of instruments.  If no instruments are specified,
then it will look at the C<RAKUDO_TELEMETRY_INSTRUMENTS> environment variable
to find specification of instruments.  If that is not available either, then
L<Thread::Instrument::Usage|/type/Thread::Instrument::Usage> and
L<Thread::Instrument::ThreadPool|/type/Thread::Instrument::ThreadPool> will be
assumed.

Instruments can be specified by either the type object of the instrument class
(e.g. C<Telemetry::Instrument::Usage>) or by a string, in which case it will
be automatically prefixed with "Telemetry::Instrument::", so "Usage" would be
the same as C<Telemetry::Instrument::Usage>.

=head2 method set-instruments

  method set-instruments(Telemetry::Sampler:D @instruments --> Nil)

Allows one to change the instruments on an existing C<Instrument::Sampler>
object.  Generally only used by calling it on the C<$*SAMPLER> dynamic variable.
Takes the same parameters as L<new>, except that specifying B<no> instruments
will actually remove all of the instruments, effectively blocking any snap taking.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
